// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IPicknPlaceHardwareGrip.cs" company="Microsoft Corporation">
// The MIT License (MIT)
// 
// Copyright (c) 2014, Microsoft Corporation
// 
// Permission is hereby granted, free of charge, to any person obtaining a copy
//  of this software and associated documentation files (the "Software"), to deal
//  in the Software without restriction, including without limitation the rights
//  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
//  copies of the Software, and to permit persons to whom the Software is
//  furnished to do so, subject to the following conditions:
// 
// The above copyright notice and this permission notice shall be included in
//  all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
//  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
//  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
//  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
//  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
//  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
//  THE SOFTWARE.
// </copyright>
// --------------------------------------------------------------------------------------------------------------------

namespace Microsoft.Robotics.Manipulation.PicknPlace
{
    using System;
    using Microsoft.Robotics.Numerics;

    /// <summary>
    /// Interface for retrieving grips for specific arm / hand hardware combinations
    /// </summary>
    public interface IPicknPlaceHardwareGrip
    {
        /// <summary>
        /// Return the tool control point pose for a grip
        /// </summary>
        /// <param name="grip">The grip</param>
        /// <param name="surfaceOffset">Surface offset</param>/// 
        /// <param name="score">Output score measure of how far the pose is to limits. Bigger is better</param>
        /// <returns>Tool control point pose</returns>
        /// <exception cref="ArgumentException">Hardware cannot execute the grip</exception>
        Pose ArmPoseFromGrip(GripState grip, double surfaceOffset, out double score);

        /// <summary>
        /// Pre grip plane from a grip plane
        /// </summary>
        /// <param name="gripPlane">Input grip plane</param>
        /// <returns>Pre grip plane</returns>
        Vector4 PreGripPlane(Vector4 gripPlane);

        /// <summary>
        /// Retrieve the pre grip from a grip
        /// </summary>
        /// <param name="grip">The grip</param>
        /// <returns>Pre grip center</returns>
        Vector3 PreGripCenter(GripState grip);

        /// <summary>
        /// Return the grip open position expressed as a fraction of the maximum open configuration expressed as a percentage
        /// in the open state.
        /// </summary>
        /// <param name="gripDimension">Dimension of the object at the grip center orthogonal to grip axis and parallel to the palm plane</param>
        /// <returns>Amount of grip opening expressed as a percent</returns>
        double GetPercentOpenForOpenState(double gripDimension);

        /// <summary>
        /// Return the grip open position expressed as a fraction of the maximum open configuration expressed as a percentage
        /// in the closed state.
        /// </summary>
        /// <param name="gripDimension">Dimension of the object at the grip center orthogonal to grip axis and parallel to the palm plane</param>
        /// <returns>Amount of grip opening expressed as a percent</returns>
        double GetPercentOpenForCloseState(double gripDimension);
    }
}
